.TH std::flat_map::try_emplace 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary"
.SH NAME
std::flat_map::try_emplace \- std::flat_map::try_emplace

.SH Synopsis
   template< class... Args >
   std::pair<iterator, bool> try_emplace( const key_type& k,          \fB(1)\fP (since C++23)
   Args&&... args );
   template< class... Args >
   std::pair<iterator, bool> try_emplace( key_type&& k, Args&&...     \fB(2)\fP (since C++23)
   args );
   template< class K, class... Args >                                 \fB(3)\fP (since C++23)
   std::pair<iterator, bool> try_emplace( K&& k, Args&&... args );
   template< class... Args >
   iterator try_emplace( const_iterator hint, const key_type& k,      \fB(4)\fP (since C++23)
   Args&&... args );
   template< class... Args >
   iterator try_emplace( const_iterator hint, key_type&& k, Args&&... \fB(5)\fP (since C++23)
   args );
   template< class K, class... Args >
   iterator try_emplace( const_iterator hint, K&& k, Args&&... args   \fB(6)\fP (since C++23)
   );

   If a key equivalent to k already exists in the container, does nothing. Otherwise,
   inserts a new element into the underlying containers c with key k and value
   constructed with args.

   1,2,4,5) Equivalent to:

 auto key_it = ranges::upper_bound(c.keys, k, compare);
 auto value_it = c.values.begin() + std::distance(c.keys.begin(), key_it);
 c.keys.insert(key_it, std::forward<decltype(k)>(k));
 c.values.emplace(value_it, std::forward<Args>(args)...);

   3,6) Equivalent to:

 auto key_it = ranges::upper_bound(c.keys, k, compare);
 auto value_it = c.values.begin() + std::distance(c.keys.begin(), key_it);
 c.keys.emplace(key_it, std::forward<K>(k));
 c.values.emplace(value_it, std::forward<Args>(args)...);

   The conversion from k into key_type must construct an object u, for which find(k) ==
   find(u) is true. Otherwise, the behavior is undefined.
   These overloads participate in overload resolution only if :
     * The qualified-id Compare::is_transparent is valid and denotes a type.
     * std::is_constructible_v<key_type, K> is true.
     * std::is_assignable_v<mapped_type&, Args...> is true.
     * For \fB(3)\fP only, std::is_convertible_v<K&&, const_iterator> and
       std::is_convertible_v<K&&, iterator> are both false.

    Information on iterator invalidation is copied from here

.SH Parameters

   k    - the key used both to look up and to insert if not found
   hint - iterator to the position before which the new element will be inserted
   args - arguments to forward to the constructor of the element

.SH Return value

   1-3) Same as for emplace.
   4-6) Same as for emplace_hint.

.SH Complexity

   1-3) Same as for emplace.
   4-6) Same as for emplace_hint.

.SH Notes

   Unlike insert or emplace, these functions do not move from rvalue arguments if the
   insertion does not happen, which makes it easy to manipulate maps whose values are
   move-only types, such as std::flat_map<std::string, std::unique_ptr<foo>>. In
   addition, try_emplace treats the key and the arguments to the mapped_type
   separately, unlike emplace, which requires the arguments to construct a value_type
   (that is, a std::pair).

   Overloads (3,6) can be called without constructing an object of type key_type.

.SH Example


// Run this code

 #include <flat_map>
 #include <iostream>
 #include <string>
 #include <utility>

 void print_node(const auto& node)
 {
     std::cout << '[' << node.first << "] = " << node.second << '\\n';
 }

 void print_result(auto const& pair)
 {
     std::cout << (pair.second ? "inserted: " : "ignored:  ");
     print_node(*pair.first);
 }

 int main()
 {
     using namespace std::literals;
     std::map<std::string, std::string> m;

     print_result(m.try_emplace( "a", "a"s));
     print_result(m.try_emplace( "b", "abcd"));
     print_result(m.try_emplace( "c", 10, 'c'));
     print_result(m.try_emplace( "c", "Won't be inserted"));

     for (const auto& p : m)
         print_node(p);
 }

.SH Output:

 inserted: [a] = a
 inserted: [b] = abcd
 inserted: [c] = cccccccccc
 ignored:  [c] = cccccccccc
 [a] = a
 [b] = abcd
 [c] = cccccccccc

.SH See also

   emplace          constructs element in-place
                    \fI(public member function)\fP
   emplace_hint     constructs elements in-place using a hint
                    \fI(public member function)\fP
   insert           inserts elements
                    \fI(public member function)\fP
                    inserts an element or assigns to the current element if the key
   insert_or_assign already exists
                    \fI(public member function)\fP
